Make SDK preview publication opt-in - #100

Summary

Replace the always-on TestPyPI preview job with two separate concerns:

• Package Check runs deterministically on every PR and on main. It runs the SDK unit tests, builds the wheel and sdist, validates them with Twine, installs the wheel in a clean environment, runs an import smoke test, and uploads the distributions as workflow artifacts.
• Publish PR Preview runs only when explicitly requested through the publish-preview label or manual workflow dispatch.

The companion CLI implementation is SocketDev/socket-python-cli#287.

Why

The previous preview check coupled code validation to TestPyPI publication and its cached Simple API. Recent uploads succeeded but the check waited for ten minutes and failed because the runner continued seeing a stale package index. Global “next .devN” discovery also allowed concurrent PRs or stale index responses to select an already-used version, producing either collisions or false-green runs that skipped the current build.

Implementation

• Preview versions now use a deterministic, globally unique .dev<run-id-and-attempt> suffix.
• Preview version injection can skip uv lock; publishing no longer depends on rewriting the dependency lock.
• The artifact is built, checked, and installed locally before publication.
• The post-upload Simple API polling loop is removed. A successful trusted upload completes the publication job; the PR comment notes that TestPyPI may take several minutes to expose the new version.
• Fork PRs cannot trigger label-based publishing.

Opt-in usage

Apply the existing publish-preview repository label to a same-repository PR to publish one preview. Maintainers can alternatively run Publish PR Preview manually with the PR number.

Review follow-up

• Manual dispatch now validates an ASCII numeric PR number, requires the default branch, rejects closed and fork PRs, and pins the exact PR head SHA before checkout.
• The preview ID guard now accepts ASCII digits only.
• CONTRIBUTING documents the same-repository and default-branch requirements.

Validation

• actionlint .github/workflows/package-check.yml .github/workflows/pr-preview.yml
• ruff check .hooks/sync_version.py
• 122 unit tests passed, 1 skipped on current main
• Wheel and sdist built successfully and passed twine check
• Wheel installed in a clean environment and passed the SDK import smoke test
• Deterministic preview version injection verified without changing uv.lock

After this merges, Package Check can be added to the branch-protection required checks.